Back to Contents        Previous        Next






24. Colour picker

(Please note that RiscOS Version 3.50 or higher is needed to use the Colour Picker.)

If you have a RiscOS Version from 3.50 onwards you will be familiar with the Colour Picker window, from applications such as !Draw - and now Dr Wimp will enable you to introduce the same features into your own applications.

Essentially, the Colour Picker is a window which, when displayed, enables the application user to choose, visually, what colour is required, from the complete range of colours available. A colour can be specified by clicking on the colour actually displayed in the window, or by specifying the proportions of the constituent colour components (in RGB, CMYK or HSV terms). These are all automatically linked in the Colour Picker window, so a simple but very comprehensive facility is offered.

Dr Wimp provides two ways of harnessing the Colour Picker: one by opening the colour picker window exactly like any other window and the other by opening it as a ‘sub-menu’ from a menu item.

The ‘colour models’
When the colour picker window is first opened, it will have a default colour already displayed and Dr Wimp allows you to specify this. Further, you can choose between specifying this initial colour in familiar ‘rgb’ values in the range 0-255 or in the values of one of the three ‘colour models’ i.e. in the RGB or CMYK or HSV ‘colour model’.

Whichever method you choose here will not limit you subsequent ability to use the whole range of the colour picker window settings once the window is open - which includes being able to change the ‘model’ etc.

Briefly:

The RGB colour ‘model’ specifies the amounts of the Red, Green and Blue components of a colour in percentage terms i.e. each in the range 0-100. (Note: not 0-255 here.)
The CMYK ‘model’ specifies the amounts of the Cyan, Magenta, Yellow and ‘Key’ (black) components of a colour in percentage terms i.e. each in the range 0-100.
The HSV ‘model’ specifies the amounts of the Hue ‘colour angle’ in the range 0-359 degrees, and the Saturation and Value components of a colour in percentage terms (0-100).

These different ‘models’ are merely different ways of specifying a colour and each tends to be used in practice by different groups of people working with colour e.g. artists, printers, scientists.


Making the colour choice
Once the user has decided which colour is wanted, he/she presses an OK button - so you, the programmer, need a means of extracting the choice from the colour picker window and into your program for further use e.g. to draw something in the chosen colour.

Dr Wimp provides two user-functions for this purpose. One provides the chosen colour output in 0-255 ‘rgb’ values and the other in the values of the ‘model’ actually selected in the colour picker window at the time the selection was made.

‘Dialogue type’
If you open the colour picker window as a ‘sub-menu’ it will, as you would expect, close automatically like any other sub-menu if you move the pointer back over the menu item from which it came - and if you click elsewhere on the screen. This is known as the ‘sub-menu dialogue type’.

If you open the colour picker window as an ordinary window, Dr Wimp also allows you to have the choice of closing it in the normal way (e.g. by clicking on its Close icon) or closing like a menu i.e. closing when a click is made elsewhere.

In all cases, the window will close automatically when you use <select> over the colour picker window’s OK or None buttons (but using <adjust> will keep it open as usual).


Now we can look at the wimp- and user-functions and we will start with the latter.

The user-functions (for reading the chosen colour)
They are:
PROCuser_colourpickerrgb(red%,green%,blue%,none%)

and
PROCuser_colourpickermodel(model%,value1,value2,value3, value4,none%)

Both of these are called automatically every time you make a colour selection in the colour picker window i.e. when the user presses OK or None.

If OK was pressed , then both user-functions will pass the values of the chosen colour in their parameters and none% will be set to 0. If None was pressed, then the currently displayed colour values in the colour picker window will still be passed, but none% will be set to 1. (So it is up to you to decide how to react to none% having a value of 1. For example, you might want to ignore the colour data in this case, or you might want to store the values in order to open the window with these values next time.)

Irrespective of the method you chose to open the colour picker window and irrespective of the actual ‘model’ currently selected in the window at the time you made your colour choice, PROCuser_colourpickerrgb will always give the values red%, green% and blue% in the range 0-255, which is often used in other wimp-functions and can therefore be conveniently passed on directly.

The parameters passed in PROCuser_colourpickermodel need a little extra explanation. They will again reflect the chosen colour values in the ‘model’ actually displayed in the colour picker window at the time the OK (or None) button is pressed - which, of course, may not be the same ‘model’ in which you specified the window to open initially. However:

model% will be either 0, 1 or 2 for RGB, CMYK or HSV respectively.
value1
,
value2
,
value3
and
value4 will be in percentage values in the range 0-100 - except that value1 will be in the range 0-359 if model% is 2 (i.e. the ‘colour angle’ in degrees in the HSV ‘model’). Also, value4 only has relevance for the CMYK ‘model’ i.e. when model% is 1 - and it will be set to -1 for other ‘models’.

The wimp-functions (for opening the colour-picker window)
Now let us look at opening the colour picker window - firstly as a normal window.

The two available wimp-functions are:

PROCwimp_opencolourpickermodel(model%,dialoguetype%,value1, value2,value3,value4,none%,x%,y%)

PROCwimp_opencolourpickerrgb(dialoguetype%,red%,green%,blue%, none%,x%,y%)

From the earlier description of the user-functions, the meaning of most of these parameters will now be clear. The values set the colour that will be initially displayed when the window first opens and also the ‘model’ that will be initially displayed. (If you use PROCwimp_opencolourpickerrgb the RGB ‘model’ will be displayed initially with the 0-255 values converted to 0-100 values). Don’t forget that value4 must always have a value assigned to it although that value will be ignored if model% is 0 or 2.

none% chooses whether the ‘None’ button is available or not and whether it is selected when the colourpicker window opens. A value of 0 means ‘None’ button will not be available for use; 1 means it will be available and initially de-selected; and 2 means it will available and initially selected.

x%/y% are simply the required screen OS coordinates for the top left corner of the opening colour picker window.

The parameter dialoguetype% determines the type of window closure that will apply and can be set to either 0 or 1. If it is 0 then the colour picker window will stay open until you close it by some means or you press OK or None. (This is called the ‘normal dialogue’.) However, if it is 1 then the window will also close if you click anywhere outside it. (This is known as the ‘menu dialogue’, for fairly obvious reasons.)

With either of these two wimp-functions, you simply call them in similar circumstances to using PROCwimp_openwindow. For example, from PROCuser_mouseclick or PROCuser_menuselection. They are perfectly straightforward to use. (You do not normally need to know the colour picker window handle but it is held, after the call, in the global variable wpickerwindow%.)
Opening the colour picker as a ‘sub-menu’ is also easy, but involves two steps.

A special global variable called wSUBMENUCOLOURPICKER% (a mouthful, but you won’t easily forget it!) has been created in the DrWimp library and is set to 1 as default. If you want the colour picker window to appear as a sub-menu to an (already defined) parent menu item, then the first step is to ‘attach’ wSUBMENUCOLOURPICKER% to that item as its sub-menu/window handle. e.g.:

PROCwimp_attachsubmenu(parentmenu%,3,wSUBMENUCOLOURPICKER%)

This action ensures that the required item (here, 3) on the parent menu (whose handle here is parentmenu%) correctly displays a sub-menu ‘arrowhead’ - and that is all it does.

The second, and final, step is to decide which of two wimp-functions you wish to use to actually cause the window to open (when you move across the just-created arrowhead) and put it into DEF PROCuser_overmenuarrow. The two wimp-functions are:

PROCwimp_opensubmenucolourpickermodel(model%,value1,value2,
value3,value4,none%,x%,y%
)

PROCwimp_opensubmenucolourpickerrgb(red%,green%,blue%,none%,
x%,y%)

As you can see, these match the two previously-described wimp-functions except that there is no dialoguetype% parameter (because, in this case, the colour picker window will always act exactly like a sub-menu i.e. it will use the ‘sub-menu dialogue’).

A typical coding might therefore be:

DEF PROCuser_overmenuarrow(rootmenu%,rootmenuitem%,RETURN nextsubmenu%,nextsubmenunumber%,parentmenuitem%,x%,y%)
CASE nextsubmenu% OF
         WHEN wSUBMENUCOLOURPICKER%
         PROCwimp_opensubmenucolourpickermodel(1,0,40,55,20,1,x%,y%)
ENDCASE
ENDPROC


This would cause the colour picker window to open when you move across its parent menu’s arrowhead - and, here, it would open with the CMYK ‘model’ showing percentage values of 0, 40, 55 and 20, which is an orangey sort of red. It will open in the same place as a conventional sub-menu, because x% and y% have been passed straight through.

As before, the two colour picker user-functions will be called when you actually select OK or None. If you did not change the above initial colour and then selected OK, PROCuser_colourpickerrgb would return 204, 102 and 64 for its red, gren and blue values i.e. in the range 0-255.


In the Examples folder there is an application called !ColPick which gives a practical demonstration of how to use the above-described facilities.









Top of page        Back to Contents        Previous        Next